接口设计规范
在接口设计规范方面，我们需要遵循 RESTful 设计原则，使用统一的接口 URL 规范，选择合适的 HTTP 请求方法，以及规范化 HTTP 请求头和请求体的内容格式。同时，我们需要注意接口的可读性和可维护性，避免接口设计过于复杂或冗余，同时确保接口的一致性和可靠性。
接口安全规范
接口安全是一个重要的问题，我们需要采取一定的措施来保护接口的安全性。在接口安全规范方面，我们需要使用适当的认证和授权方式来限制接口访问，管理 API 密钥并限制其权限，以及采用加密传输技术来保证数据传输的安全性。
此外，我们还可以使用x-sp-signature HTTP 请求头，用于验证请求的身份并确保在传输过程中没有被篡改。该头部的值是使用secret作为密钥对用户 Id 进行 HMAC-SHA1 散列后进行 Base64 编码的结果。
除了x-sp-signature请求头之外，我们还支持使用x-sp-sign-version请求头来指定签名的算法版本。该请求头的值应该是一个字符串，表示签名算法的版本号。当前支持的算法版本为 v1。如果没有指定该请求头，将默认使用 v1 版本的 HMAC-SHA1 签名算法进行计算。
计算方法（v1）
计算 x-sp-signature 头部值的步骤如下：
- 获取用户 Id 作为输入，该值是一个字符串。例如 "1000268"
- 使用密钥secret作为密钥计算用户 Id 的HMAC-SHA1散列。
- 将结果散列值以 Base64 格式进行编码。
- 将编码后的结果设置为 x-sp-signature 的值。
Secret 的值如何获取
- 登录【算盘】，点击右上角图标，如下图所示：
- 复制 AccessKeySecret 的值，即为 secret
OS 组件集成（示例）
该集成功能用于在【算盘】-【我的组件】下创建自定义组件。
请求
| 基本 | |
|---|---|
| HTTP URL | https://spnext.xuelangyun.com/api/integration/component |
| HTTP Method | POST |
| 支持的应用类型 | 仅应用开发 |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| x-sp-user-id | string | 是 | 用户 Id，例如 1000268 |
| x-sp-sign-version | string | 是 | 版本。默认字符串：v1 |
| x-sp-signature | string | 是 | 参照 x-sp-signature 请求头。示例值：ShuGRM2br4o5KQWbWTBhMGxP/-w= |
| Content-Type | string | 是 | 固定值："application/json; charset=utf-8" |
请求体
| 参数 | 参数类型 | 必须 | 说明 |
|---|---|---|---|
| name | string | 是 | 组件名称 |
| image | string | 是 | 组件镜像 |
| cmd | string | 是 | 启动命令 |
| type | string | 否 | 组件类型，默认应用组件 |
| dir | string | 否 | 创建的目录，默认根目录 |
请求体示例
{
"name":"component-name-from-open-api",
"dir":2,
"type":"service",
"image":"nacos:latest",
"cmd":"java -jar demo.jar"
}
响应
响应体
| 参数 | 说明 |
|---|---|
| success | 布尔类型。是否成功 |
| data | 返回值，见示例 |
| message | 错误信息 |
响应体示例
示例：
下面脚本，替换 secret，userId， image，cmd 后可以直接运行，创建组件。
#!/bin/bash
secret="VE9CSyPv40IBzCkig06T2WpM7"
userId="10004"
image="registry.xuelangyun.com/shuzhi-amd64/matrix-transpose:latest"
cmd="node transpose.js"
name="矩阵转置"
signature=$(printf "$userId" | openssl dgst -sha1 -hmac "$secret" -binary | base64)
echo "Signature: $signature"
curl --location --request POST 'http://sp1.xuelangyun.com:30080/api/integration/component' \
--header "x-sp-user-id: ${userId}" \
--header "x-sp-signature: ${signature}" \
--header 'x-sp-sign-version: v1' \
--header 'content-type: application/json; charset=UTF-8' \
--header 'Accept: */*' \
--data-raw "{\"name\":\"${name}\",\"dir\":2,\"type\":\"service\",\"fromAppId\":null,\"image\":\"${image}\",\"cmd\":\"${cmd}\"}"